<?php
/**
 * Image manipulation & rendering library.
 *
 * @author Martin "DevelX" Jurča
 * @version 2009-03-21
 */
interface Image {
    /**
     * Renders the image according to given parameters. Returns the rendered
     * image as bytestream.
     *
     * @param Array $parameters Parameters for the renderer. Each item should
     *        be an array representing one image operation. The operation name
     *        is 'cmd' property of operation array. Possible operations are:
     *        import, save, resize, watermark, crop, filter, rotate. Each
     *        operation name is the same as method name of this library. All
     *        operation method parameters are required and are stored by keys
     *        0, 1, ... (n - 1); where n is number of method parameters.
     * @param String $output If set to false, the image content would be sent
     *        to standard output. Set this parameter to string containing url
     *        in order to send the image content to a file.
     * @return String Bytestream content of rendered image file.
     */
    public static function render(&$parameters, $output);

    /**
     * Imports external image file.
     *
     * @param String $url Image file to import.
     * @return boolean True on success, false otherwise.
     */
    public static function import($url);

    /**
     * Resizes the loaded image.
     *
     * @param int $width New image width.
     * @param int $height New Image height.
     * @param boolean $border When set to true and $keepAspectRatio is set to
     *        true, the method adds borders to the image of specified color in
     *        order to mantain the desired size. If set to false and
     *        $keepAspectRatio is set to true, the result image size may differ
     *        from desired becouse of mantaining the same aspect ratio.
     * @param Array $backgroundColor Color of the added border. If set to -1,
     *        the method uses default background color set in configuration.
     *        Index 0 is red, 1 is green, 2 is blue, all range from 0 to 255.
     * @param boolean $keepAspectRation When set to true, method keeps the
     *        original aspect ratio of the image, sometimes resulting in adding
     *        border of some color and shifting the resized image to center.
     * @return boolean True on success, false otherwise.
     */
    public static function resize($width, $height, $border = false,
            $backgroundColor = -1, $keepAspectRatio = true);

    /**
     * Saves the image into file.
     *
     * @param String $url Url to the file.
     * @param String $format Image file format.
     * @param int $quality If format supports quality setting, use this
     *        parameter to set the output quality.
     * @return boolean True on success, false otherwise.
     */
    public static function save($url, $format = 'jpg', $quality = -1);

    /**
     * Watermarks the image.
     *
     * @param String $watermarkUrl URL to watermark image.
     * @param int $x X position of the watermark.
     * @param int $y Y position of the watermark.
     * @param int $opacity Opacity of the watermark.
     * @return boolean True on success, false otherwise.
     */
    public static function watermark($watermarkUrl, $x, $y, $opacity = 100);

    /**
     * Crops the image to new size.
     *
     * @param int $width New image size.
     * @param int $height New image
     * @param int $shiftX How to shift the image on x-axes.
     * @param int $shiftY How to shift the image on y-axes.
     * @return boolean True on success, false otherwise.
     */
    public static function crop($width, $height, $shiftX, $shiftY);

    /**
     * Applies filter to the image. Available filters (and their arguments):
     *   IMG_FILTER_NEGATE ()
     *     Reverses all colors of the image.
     *   IMG_FILTER_GRAYSCALE ()
     *     Reverses all colors of the image.
     *   IMG_FILTER_BRIGHTNESS (arg1)
     *     Changes the brightness of the image. Use arg1 to set the level of
     *     brightness.
     *   IMG_FILTER_CONTRAST (arg1)
     *     Changes the contrast of the image. Use arg1 to set the level of
     *     contrast.
     *   IMG_FILTER_COLORIZE (arg1, arg2, arg3, arg4)
     *     Like IMG_FILTER_GRAYSCALE, except you can specify the color. Use
     *     arg1, arg2 and arg3 in the form of red, blue, green and arg4 for the
     *     alpha  channel. The range for each color is 0 to 255.
     *   IMG_FILTER_EDGEDETECT ()
     *     Uses edge detection to highlight the edges in the image.
     *   IMG_FILTER_EMBOSS ()
     *     Embosses the image.
     *   IMG_FILTER_GAUSSIAN_BLUR ()
     *     Blurs the image using the Gaussian method.
     *   IMG_FILTER_SELECTIVE_BLUR ()
     *     Blurs the image.
     *   IMG_FILTER_MEAN_REMOVAL ()
     *     Uses mean removal to achieve a "sketchy" effect.
     *   IMG_FILTER_SMOOTH (arg1)
     *     Makes the image smoother. Use arg1 to set the level of smoothness.
     *
     * @param int $filter Filter to apply.
     * @param Array $args Array of optional arguments for the filter. Keys of
     *        the array should be number from 0 inclusive to 4 exclusive.
     * @return boolean True on success, false otherwise.
     */
    public static function filter($filter, $args);

    /**
     * Rotates the image by specified angle.
     *
     * @param float $angle Angle of rotation, in degrees.
     * @param Array $background Background color. If not specified, the method
     *        uses default background color specified in config. Same format
     *        as used for resize method.
     * @return boolean True on success, false otherwise.
     */
    public static function rotate($angle, $background = -1);

    /**
     * Returns width of the loaded image.
     *
     * @return int Width of the image.
     */
    public static function getWidth();

    /**
     * Return height of the loaded image.
     *
     * @return int Height of the image.
     */
    public static function getHeight();
}
?>
